✨ (alpha update) initial code for the `alpha update` command #4871

vitorfloriano · 2025-06-13T04:06:39Z

The kubebuilder alpha update command performs a three-way Git merge to upgrade a project to a newer Kubebuilder version while preserving user-defined code. The process is fully automated and follows these main steps:

1. Ancestor Branch (baseline scaffold)

Created from the specified base branch (default is main)
Cleans the branch, keeping only .git and PROJECT
Downloads and uses the old Kubebuilder release to re-scaffold the project
Commits the result — this branch serves as the synthetic ancestor

2. Original Branch (user’s current code)

Created from the ancestor branch
Checks out all files from the user’s base branch (git checkout main -- .)
Stages and commits the current project state

3. Upgrade Branch (target scaffold)

Created from the ancestor branch
Cleaned similarly (preserving only .git and PROJECT)
Uses the new Kubebuilder release to re-scaffold the project
Stages and commits the upgraded scaffold

4. Merge Branch (final result)

Created from the upgrade branch
Merges in the original branch (user code)
If conflicts occur:
- The user is notified and must resolve them manually
If the merge is clean:
- The result is committed automatically

This command provides a reliable and repeatable way to upgrade project scaffolding while preserving user customizations. Flags like --from-version, --to-version, and --from-branch offer full control over the versions and branches involved in the update.

Example:

$ kubebuilder alpha update --from-version v4.5.2
WARN No --from-branch specified, using 'main' as default 
INFO Checking if is a git repository              
INFO Checking if branch has uncommitted changes   
INFO Binary version v4.5.2 is available           
INFO Binary version v4.6.0 is available           
INFO Checking out base branch: main               
INFO Using branch names:                          
INFO   Ancestor: tmp-ancestor-29-06-25-20-46      
INFO   Original:  tmp-original-29-06-25-20-46     
INFO   Upgrade:  tmp-upgrade-29-06-25-20-46       
INFO   Merge:    tmp-merge-29-06-25-20-46         
INFO Created and checked out ancestor branch      
INFO Cleaning all files and folders except .git and PROJECT 
INFO Successfully cleanup files in ancestor branch 
INFO Downloading the release v4.5.2 binary from: https://github.com/kubernetes-sigs/kubebuilder/releases/download/v4.5.2/kubebuilder_darwin_arm64 
INFO release binary version v4.5.2 successfully downloaded to /var/folders/n4/j272tr6d7hq63mf7_skv6zr80000gn/T/kubebuilderv4.5.2-520327151/kubebuilder 
INFO Downloaded binary kept at /var/folders/n4/j272tr6d7hq63mf7_skv6zr80000gn/T/kubebuilderv4.5.2-520327151 for debugging purposes 
INFO Generating project with version v4.5.2       
WARN Using current working directory to re-scaffold the project 
WARN This directory will be cleaned up and all files removed before the re-generation 
INFO Cleaning directory:/Users/camilam/go/src/github/camilamacedo86/wordpress-operator 
INFO Running cleanup:
$ sh -c rm -rf /Users/camilam/go/src/github/camilamacedo86/wordpress-operator/* 
INFO kubebuilder init:
$ kubebuilder init --plugins go.kubebuilder.io/v4 --domain my.domain --repo github/camilamacedo86/wordpress-operator 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO Get controller runtime:
$ go get sigs.k8s.io/[email protected] 
INFO Update dependencies:
$ go mod tidy           
Next: define a resource with:
$ kubebuilder create api
INFO kubebuilder create api:
$ kubebuilder create api --plural wordpresses --group example.com --version v1 --kind Wordpress --resource --namespaced --controller 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO api/v1/wordpress_types.go                    
INFO api/v1/groupversion_info.go                  
INFO internal/controller/suite_test.go            
INFO internal/controller/wordpress_controller.go  
INFO internal/controller/wordpress_controller_test.go 
INFO Update dependencies:
$ go mod tidy           
INFO Running make:
$ make generate                
mkdir -p /Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin
Downloading sigs.k8s.io/controller-tools/cmd/[email protected]
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new API and generate the manifests (e.g. CRDs,CRs) with:
$ make manifests
INFO kubebuilder create webhook:
$ kubebuilder create webhook --plural wordpresses --group example.com --version v1 --kind Wordpress --programmatic-validation --defaulting 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO internal/webhook/v1/wordpress_webhook.go     
INFO internal/webhook/v1/wordpress_webhook_test.go 
INFO internal/webhook/v1/webhook_suite_test.go    
INFO Update dependencies:
$ go mod tidy           
INFO Running make:
$ make generate                
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new Webhook and generate the manifests with:
$ make manifests
INFO Grafana plugin not found, skipping migration 
INFO Deploy-image plugin not found, skipping migration 
INFO Successfully ran alpha generatev4.5.2        
INFO Running make manifests:
$ make manifests     
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
INFO Running make generate:
$ make generate       
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
INFO Running make fmt:
$ make fmt                 
go fmt ./...
INFO Running make vet:
$ make vet                 
go vet ./...
INFO Running make lint-fix:
$ make lint-fix       
Downloading github.com/golangci/golangci-lint/cmd/[email protected]
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/golangci-lint run --fix
INFO Successfully committed tmp-ancestor-29-06-25-20-46 with clean scaffolding 
INFO Successfully checked out tmp-original-29-06-25-20-46 
INFO Successfully checked out content from main onto tmp-original-29-06-25-20-46 branch 
INFO Successfully staged all changes in current   
INFO Successfully committed changes in tmp-original-29-06-25-20-46 
INFO Successfully checked out tmp-upgrade-29-06-25-20-46 off tmp-ancestor-29-06-25-20-46 
INFO Cleaning all files and folders except .git and PROJECT 
INFO Successfully cleanup files in ancestor branch 
INFO Downloading the release v4.6.0 binary from: https://github.com/kubernetes-sigs/kubebuilder/releases/download/v4.6.0/kubebuilder_darwin_arm64 
INFO release binary version v4.6.0 successfully downloaded to /var/folders/n4/j272tr6d7hq63mf7_skv6zr80000gn/T/kubebuilderv4.6.0-603848834/kubebuilder 
INFO Downloaded binary kept at /var/folders/n4/j272tr6d7hq63mf7_skv6zr80000gn/T/kubebuilderv4.6.0-603848834 for debugging purposes 
INFO Generating project with version v4.6.0       
WARN Using current working directory to re-scaffold the project 
WARN This directory will be cleaned up and all files removed before the re-generation 
INFO Cleaning directory:/Users/camilam/go/src/github/camilamacedo86/wordpress-operator 
INFO Running cleanup:
$ sh -c rm -rf /Users/camilam/go/src/github/camilamacedo86/wordpress-operator/* 
INFO kubebuilder init:
$ kubebuilder init --plugins go.kubebuilder.io/v4 --domain my.domain --repo github/camilamacedo86/wordpress-operator 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO Get controller runtime:
$ go get sigs.k8s.io/[email protected] 
INFO Update dependencies:
$ go mod tidy           
Next: define a resource with:
$ kubebuilder create api
INFO kubebuilder create api:
$ kubebuilder create api --plural wordpresses --group example.com --version v1 --kind Wordpress --resource --namespaced --controller 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO api/v1/wordpress_types.go                    
INFO api/v1/groupversion_info.go                  
INFO internal/controller/suite_test.go            
INFO internal/controller/wordpress_controller.go  
INFO internal/controller/wordpress_controller_test.go 
INFO Update dependencies:
$ go mod tidy           
INFO Running make:
$ make generate                
mkdir -p /Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin
Downloading sigs.k8s.io/controller-tools/cmd/[email protected]
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new API and generate the manifests (e.g. CRDs,CRs) with:
$ make manifests
INFO kubebuilder create webhook:
$ kubebuilder create webhook --plural wordpresses --group example.com --version v1 --kind Wordpress --programmatic-validation --defaulting 
INFO Writing kustomize manifests for you to edit... 
INFO Writing scaffold for you to edit...          
INFO internal/webhook/v1/wordpress_webhook.go     
INFO internal/webhook/v1/wordpress_webhook_test.go 
INFO internal/webhook/v1/webhook_suite_test.go    
INFO Update dependencies:
$ go mod tidy           
INFO Running make:
$ make generate                
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
Next: implement your new Webhook and generate the manifests with:
$ make manifests
INFO Grafana plugin not found, skipping migration 
INFO Deploy-image plugin not found, skipping migration 
INFO Successfully ran alpha generatev4.6.0        
INFO Running make manifests:
$ make manifests     
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
INFO Running make generate:
$ make generate       
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
INFO Running make fmt:
$ make fmt                 
go fmt ./...
INFO Running make vet:
$ make vet                 
go vet ./...
INFO Running make lint-fix:
$ make lint-fix       
Downloading github.com/golangci/golangci-lint/v2/cmd/[email protected]
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/golangci-lint run --fix
0 issues.
INFO Successfully staged changes in tmp-upgrade-29-06-25-20-46 
INFO Successfully committed tmp-upgrade-29-06-25-20-46 with clean scaffolding 
INFO Checked out merge branch: tmp-merge-29-06-25-20-46 
INFO Merging in original code (tmp-original-29-06-25-20-46) into merge branch (tmp-merge-29-06-25-20-46) 
INFO Running make manifests:
$ make manifests     
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen rbac:roleName=manager-role crd webhook paths="./..." output:crd:artifacts:config=config/crd/bases
INFO Running make generate:
$ make generate       
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/controller-gen object:headerFile="hack/boilerplate.go.txt" paths="./..."
INFO Running make fmt:
$ make fmt                 
go fmt ./...
INFO Running make vet:
$ make vet                 
go vet ./...
INFO Running make lint-fix:
$ make lint-fix       
/Users/camilam/go/src/github/camilamacedo86/wordpress-operator/bin/golangci-lint run --fix
0 issues.

k8s-ci-robot · 2025-06-13T04:06:46Z

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by: vitorfloriano
Once this PR has been reviewed and has the lgtm label, please assign kavinjsir for approval. For more information see the Code Review Process.

The full list of commands accepted by this bot can be found here.

Needs approval from an approver in each of these files:

OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

k8s-ci-robot · 2025-06-13T04:06:48Z

Hi @vitorfloriano. Thanks for your PR.

I'm waiting for a kubernetes-sigs member to verify that this patch is reasonable to test. If it is, they should reply with /ok-to-test on its own line. Until that is done, I will not automatically test new commits in this PR, but the usual testing commands by org members will still work. Regular contributors should join the org to skip this step.

Once the patch is verified, the new status will be reflected by the ok-to-test label.

I understand the commands that are listed here.

Instructions for interacting with me using PR comments are available here. If you have questions or suggestions related to my behavior, please file an issue against the kubernetes-sigs/prow repository.

pkg/cli/alpha/update.go

pkg/cli/alpha/internal/update.go

pkg/cli/alpha/update.go

pkg/cli/alpha/internal/update.go

camilamacedo86

/ok-to-test

@vitorfloriano great work 🎉 — very solid progress! Amazing ⭐ 🚀

I’ve added some comments to the PR. Once those are addressed, the next step would be to implement a happy path test to validate the new command — similar to the structure used in:

👉 https://github.com/kubernetes-sigs/kubebuilder/tree/master/test/e2e/alphagenerate

How can we do the test:

Following some steps and references to help you out:

Create a project using Kubebuilder Latest release
Ref: generate_test.go#L231-L239
Init a new API within the project
Ref: generate_test.go#L208-L229
Use plugin utils to modify the controller
Instead of changing the whole project, we can inject custom reconcile logic into the controller file. Example from this PR commit:
camilamacedo86/wordpress-operator@380c8c9
Call the new alpha update command
Verify the results:
- The project should reflect the merged scaffold based on the latest version.
  Ref: generate_test.go#L437-L440
  (no errors were faced)

Please let me know if you’d like to pair or discuss any of this further. Happy to help 😄

pkg/cli/alpha/internal/update/utils.go

pkg/cli/alpha/internal/update/update.go

This commit introduces the `kubebuilder alpha update` command, which enables users to upgrade their Kubebuilder projects via a 3-way Git merge strategy. The update flow: - Creates an 'ancestor' branch based on the original scaffold version - Extracts the user's current project state into a 'current' branch - Generates a fresh scaffold using the target version in the 'upgrade' branch - Merges changes into a 'merge' branch, preserving user code and applying updates This mechanism allows users to safely adopt new scaffolding and maintain their custom logic with minimal manual effort.

k8s-ci-robot added the cncf-cla: yes Indicates the PR's author has signed the CNCF CLA. label Jun 13, 2025

k8s-ci-robot requested review from rashmigottipati and varshaprasad96 June 13, 2025 04:06

k8s-ci-robot added the needs-ok-to-test Indicates a PR that requires an org member to verify it is safe to test. label Jun 13, 2025

k8s-ci-robot added the size/L Denotes a PR that changes 100-499 lines, ignoring generated files. label Jun 13, 2025

camilamacedo86 reviewed Jun 13, 2025

View reviewed changes

pkg/cli/alpha/update.go Outdated Show resolved Hide resolved

camilamacedo86 reviewed Jun 13, 2025

View reviewed changes

pkg/cli/alpha/update.go Outdated Show resolved Hide resolved

camilamacedo86 reviewed Jun 13, 2025

View reviewed changes

pkg/cli/alpha/update.go Outdated Show resolved Hide resolved

camilamacedo86 reviewed Jun 13, 2025

View reviewed changes

pkg/cli/alpha/internal/update.go Outdated Show resolved Hide resolved

camilamacedo86 reviewed Jun 13, 2025

View reviewed changes

pkg/cli/alpha/update.go Outdated Show resolved Hide resolved

camilamacedo86 reviewed Jun 13, 2025

View reviewed changes

pkg/cli/alpha/internal/update.go Outdated Show resolved Hide resolved

camilamacedo86 reviewed Jun 13, 2025

View reviewed changes

pkg/cli/alpha/internal/update.go Outdated Show resolved Hide resolved

camilamacedo86 reviewed Jun 13, 2025

View reviewed changes

pkg/cli/alpha/internal/update.go Show resolved Hide resolved